Cream of the Crop 1/Cream of the Crop 1.iso/PROGRAM/GUI_LIBR.ARJ/GUI_LIB.DOC

Text File | 1992-08-17 | 29KB | 824 lines

****************************************************************************

                 Documentation for
        GUI_LIB Library for Borland C++ and Turbo C++
                Version 1.0
****************************************************************************










All files included on this distribution diskette are copyrighted by
LUDICROUS DATA - June, 1992 except EGAVGA.BGI, GOTH.CHR, and LITT.CHR.

    File contained herein include:
        GUI_LIB.LIB             The library file itself
        GUI_LIB.DOC             This file
        DEMO.EXE                Demonstration file
        DEMO.C                  Source code for DEMO.EXE
        *.ICN                   Support files for the demo
        *.BTN                   Support files for the demo
        GUI_LIB.H               Header file needed to use
                    GUI_LIB functions and objects
        REGISTER.DOC            Product registration form
        ICONEDIT.EXE            The ICONEDIT program
        ICONEDIT.DOC            ICONEDIT documentation
        EGAVGA.BGI              Borland BGI file for 640x480
                    graphics. This file is included
                    for the use of the demo program
                    only.
        GOTH.CHR                These files are used in the
        LITT.CHR                ICONEDIT program.












    Congratulations! You have just received one of the finest graphics
    libraries available for use with Borland C++ and Borland's Turbo C++
    compilers. Using the GUI_LIB library will enable you to create
    graphic based applications to run in DOS just as easily as creating
    text based applications. The objects included in the library are all
    familiar objects, found in many commercially available software
    packages. They include pushbuttons, icons, text entry fields, and
    bitmaps to name just a few. Some of the features in this library are
    found nowhere else! Now you can harness the power and intuitiveness
    of the Graphic User Interface for use in your applications. From
    paint programs to databases, all of your programs can benefit from
    the use of graphics.

    If you have not already done so, I would suggest that you stop
    reading this documentation for a moment to check out the demo
    provided on the distribution diskette. The name of the demo is
    simply DEMO.EXE. In order to run the demo you must first have
    loaded your mouse driver. Any Microsoft, Logitech, or compatible
    mouse will be fine. Also, be sure that the file EGAVGA.BGI is
    in the same directory as the DEMO.EXE file. Then from the DOS prompt
    type DEMO <ENTER>. The demo highlights most of the objects in
    the library. After viewing the demo, return to the documentation.


                SHAREWARE
****************************************************************************

    The GUI_LIB library and it's included files are being distributed as
    Shareware. They are complete and not crippled in any way. You are free
    to use these files for a 30 day period free of charge. You may not,
    however, distribute any works created with these files in any way,
    shape or form until you have registered your copy of the package.
    If after 30 days you decide to continue using the files in this
    package you are obligated to register with the author. The concept
    of Shareware helps to keep the cost of quality software low. Please
    do your part by registering this software. Use of the software
    contained in this package after 30 days without registration will
    bring about sever penalties.

    This software package is comparable with many retail libraries
    costing hundreds of dollars. It is through the concept of Shareware
    that I am able to bring this software to you at a much reduced cost.
    What's more, registered users will receive upgrades free of cost
    rather than at an upgrade cost.

    The price of this package is as follows:

        Single user license - $25
            includes free copy of the next major upgrade of the
            package.

        Corporate user license - $50
            includes free copy of the next major upgrade of the
            package.


    Please use the registration form included with this package to
    register your copy. The form can be found in the file REGISTER.DOC.

    Thank you

    If you like this product you may also wish to order the
    ObjectEase library also from this author. This library makes it
    easy to migrate into the realm of C++ programming by offering
    the widest range of classes available in any library at any
    cost. Include a note on your registration form to receive a demo
    of the ObjectEase library.



            Use of the GUI_LIB library

    In order to utilize the objects and functions in the GUI_LIB
    library you need only add the GUI_LIB library to your project,
    and include the header file in your program code. You can then
    declare object instances and call the functions as you would with
    any other library. You must, of course, first initialize the
    graphics mode with a call to initgraph(). The GUI_LIB library file
    was compiled under the large memory model using Borland C++ 3.0
    and should be included only in projects that are also to be compiled
    for the large memory model. This is because the use of graphics
    can be very memory intensive and the large memory model gives the
    program access to all of the available RAM, not just a single 64K
    data segment.

    This documentation is divided into sections describing each of the
    various graphic objects followed by a description and examples of
    all of the methods that may be used with the object. Please take
    special note of the example fragments as they may be of great help
    to you in getting to know the proper use of these objects and
    methods.










****************************************************************************
                   PANELS
****************************************************************************

    Panels can be associated with pop-up windows in a text environment.
    They serve to contain and draw attention to other objects such as
    text or pushbuttons. The class Panel is declared in the header
    file GROBJECT.H as:

class Panel:public Point
{
    protected:
        int w;                          WIDTH
        int h;                          HEIGHT
        int in_or_out;                  CONCAVE or CONVEX
        int thick_or_thin;              BORDER STYLE
    public:
        Panel();
        ~Panel();
        virtual void show();
        void init(int xpos,int ypos,int width,int height,
              int inorout,int thickorthin);
};


    The class POINT from which Panel is derived is the base class for
    all of the graphic objects in this library.

    In order to facilitate the initialization of the inorout and
    thickorthin variables the definitions IN, OUT, THICK and THIN
    may be used. These are defined in the header file.

    To declare an instance of class PANEL and display it in your
    application follow the example in the following code fragment.

    Panel mypanel;
    mypanel.init(10,10,100,100,IN,THICK);
    mypanel.show();

    It's just that simple. Remember that the graphics mode must first
    be initialized by a call to initgraph. If you are unfamiliar with
    this function consult your compiler documentation.

    All of the objects in this library contain the method "init".
    You must call "init" with the proper parameters before trying
    to display the object. There's no telling what might happen if
    you try to display an uninitialized object.








****************************************************************************
                 BEVELS
****************************************************************************

    Bevels are just like panels with a more decorative border. All
    calls to their methods are identical except that a call to
    Bevel.init() takes one less parameter. You do not need to specify
    IN or OUT because Bevel borders always go out. Here is the
    definition. I'll skip an example as you can easily follow the
    Panel example and make appropriate substitutions.

class Bevel:public Point
{
    private:
        int w;                          WIDTH
        int h;                          HEIGHT
        int thick_or_thin;              STYLE OF BORDER
        Panel outerbevel;
        Panel innerbevel;
    public:
        void init(int,int,int,int,int);
        virtual void show();
};





****************************************************************************
                 PUSHBUTTONS
****************************************************************************

    Pushbuttons simulate keyboard keys on the screen. They serve to
    get user input for a variety of purposes. They are very intuitive
    and can display either a text title or a graphic image.

The header file definition of the class Button is:

class Button:public Point
{
  protected:
    int state,                  UP or DOWN
    int sizex,                  WIDTH
    int sizey;                  HEIGHT
    char btntxt[40];            TEXT ID
    int  file_text;             TEXT ID or GRAPHIC IMAGE
    void *picture;              BUFFER CONTAINING GRAPHIC IMAGE
    void getpic(char*);
  public:
    Button();
    ~Button();
    virtual void show();
    virtual void press();
    void init(int xpos,int ypos,char* text,int);
    int hit();
};

    To declare an instance of class Button you need to supply the
    parameters for the upper left x and y positions, a string which
    either represents the text to be displayed on the button or the
    name of the file containing the image to be used on the button,
    and an integer flag representing whether or not the last parameter
    refers to text or a filename.

The definitions TEXT and IMAGE can be used in this parameter and are
defined in the header file.

    Consider this example:

    Button textbutton;
    textbutton.init(10,10," EXIT ",TEXT);
    textbutton.show();

    This would create and display a button that said " EXIT " on it.

    Consider this:

    Button graphbutton;
    graphbutton.init(10,10,"EXIT",IMAGE);
    graphbutton.show();

    This would create and display a button containing the image stored
    in the file "EXIT.BTN". The file extension should not be included
    in the parameter as ".BTN" is the assumed extension. The graphic
    file must be present on the disk before trying to call this function.
    Using the ICONEDIT program supplied with this package you can very
    easily create these graphics to be included on buttons.

    Note that you do not need to specify the width and height of buttons.
    If you are using text labels the button width is determined
    automatically to accomodate up to 40 characters, and if your are
    using graphics the button defaults to 20x20. This is the size of
    the button graphics created by the ICONEDIT program.

    Pressing the button is usually done with the mouse cursor, however,
    you may find it useful to use some other trigger to press the button.
    The button method "hit()" determines if the mouse cursor is within the
    boundaries of the button. For a detailed discussion on the use of the
    mouse functions see the appropriate section of this documentation. If
    you don't understand all of the functions in this next code fragment
    you can find explanations elsewhere in this document.

    Button mybutton;                       DECLARES INSTANCE OF BUTTON
    mybutton.init(10,10,"EXIT",TEXT);      INITIALIZES MYBUTTON
    mybutton.show();                       DISPLAYS MYBUTTON ON SCREEN

    while(!kbhit()) {                      DO THIS WHILE NO KEYS ARE HIT
      if(leftmousekeypressed()) {          IF THE LEFT MOUSE KEY IS
                           PRESSED
        if(mybutton.hit()) {               IF MOUSE CURSOR IS ON MYBUTTON
          mybutton.press();                DISPLAY MYBUTTON AS PRESSED
          while(leftmousekeypressed());    WAIT UNTIL LEFT MOUSE KEY HAS
                           BEEN RELEASED
          mybutton.show();                 DISPLAY MYBUTTON IN NORMAL
                           STATE
          }
      }
    }

    Immediately after restoring the button to the normal (undepressed)
    state the program can branch to take whatever action the button
    calls for.  By using the Button method "press()" all of the
    redrawing and repositioning of the text and/or graphic images is
    handled automatically by the GUI_LIB library.





****************************************************************************
                  COLORBUTTONS
****************************************************************************

    Colorbuttons don't do much except tell you when they are hit and
return their current color. This is very useful if you are coding a paint
program and need some way to set the current foreground and background colors.
I'm sure you can find some other good uses for this class as well.

    The header definition of class Colorbutton is:


class Colorbutton:public Point
{
    protected:
        int color;
        int width;
        int height;
    public:
        void init(int,int,int,int,int);
        void show(int);
        int  hit();
        int getcolor();
        };

    Call "init()" with integer parameters for the x and y position,
the width, the height, and the color of the button. Call "show()" with
and integer value representing the color of the rectangle you wish to
have surrounding the Colorbutton. By manipulating this value you can
effectively show an "active" Colorbutton in a row of Colorbuttons. "Hit()"
simply returns whether or not the mouse cursor is in the Colorbutton
area, and "getcolor()" return the color of the Colorbutton.

    A quick way to make a color selection bar is as follows:

Colorbutton colorarray[16];
for(int i=0;i<16;i++) {
    colorarray[i].init(100+(i*20),100,20,20,i);
    colorarray[i].show(15);
    }





****************************************************************************
                 ICONS
****************************************************************************

    Icons can be used in much the same way as buttons. They will always
    contain a graphic image, although text can be a part of the graphic.
    They are not 3 dimensional like pushbuttons.

    The graphic images for these Icon objects are created using the
    ICONEDIT program. This program produces 32x32 pixel icons that can be
    single or multi-framed. More on this in a moment.

The definition of the Icon class is:

class Icon:public Point
{
    protected:
        int state;                      SELECTED OR NOT
    public:
        void far *picture;              BUFFER CONTAINING GRAPHIC
    Icon();
    ~Icon();
        void init(int xpos,int ypos,char* fname);
        void show();
        void choose();
        int hit();
        int ispressed();
    };

    Like the other graphic objects, the Icon class must first be
    initialized with a call to "init()." Init() takes three parameter,
    the x and y coordinates of the upper left corner, and the file name
    of the file containing the graphic image for the icon. The filename
    parameter should be given without an extension as the default
    extension ".ICN" is assumed. The file named in this parameter must
    exist in the current directory.

    Let's look at a short example:

    Icon myicon;
    myicon.init(10,10,"paint");
    myicon.show();

    This example declares an instance of class Icon using the file
    "paint.icn" as the graphic, and then displays the icon.

    As with the pushbutton, the method "hit()" determines if the
    mouse cursor is within the boundaries of the icon. If it is,
    and if a mouse key is pressed, we can change the appearance of
    the icon to mark it as selected using the method "choose()." Here's
    a quick example, similar to that presented for the pushbutton:

    Icon myicon;
    myicon.init(10,10,"paint");
    myicon.show();

    while(!kbhit()) {
        if(leftmousekeypressed()) {
            if(myicon.hit()) {
                if(!myicon.ispressed()) {
                    myicon.choose();
                    while(leftmousekeypressed());
                    myicon.show();
                    }
                }
            }
        }

    Usually when an icon has been selected you will want to make
    sure that the last icon to be selected gets reset to its normal
    state with a call to "show()." Whatever action needs to be taken
    as a result of the icon's selection can be done after the call to
    "choose()." The method "ispressed()" simply returns whether or not
    the icon is already displayed in its selected state.







****************************************************************************
                 ACTICONS
****************************************************************************

    Acticons are exactly like Icons except that instead of simply
    reversing their image to mark them as the selected icon, they
    become animated. Acticons are created using the ICONEDIT program.
    They are created in the same manner as an Icon, but instead of just
    a single frame graphic, they contain several (up to 32) frames.

Acticons are defined in the header file as follows:

class Acticon:public Icon
{
    protected:
        void *picture[32];              GRAPHICS BUFFERS
        int state;                      SELECTED OR NOT
        int numpix;                     NUMBER OF FRAMES
    public:
        Acticon();
        ~Acticon();
        void init(int,int,char*);
        void show(int);
        void choose();
        int ispressed();
        void animate(int);
        void backforth(int);
    };


    Like Icons, they are initialized with a call to "init()" with
    parameters for the upper left x and y coordinates, and the file
    name containing the graphic images. When you call "show()", however,
    you must supply an integer parameter specifying which frame to
    display. Usually you will want to make this frame 0 because if
    you call "choose()" the negative image of frame 0 will be displayed
    by default.

    For example:

    Acticon myicon;
    myicon.init(10,10,"paint");
    myicon.show(0);

    Just like an Icon except for the parameter in the call to "show()."
    If you want to use choose to show the reverse image of the Acticon
    it is done the same as it is for class Icon. If however you want
    to animate the Acticon you must call "animate()" or "backforth()."
    Both of these methods will put the Acticon in motion. "Animate()"
    will display the frames in ascending order and then restart at
    frame 0. "Backforth()" will display the frames in ascending order,
    but when it reaches the last frame it will then display the frames
    in reverse order back to frame 0. Both of these methods take a
    single parameter which specifies the delay between displaying each
    frame. This delay is expressed in eighteenths of a second. The
    lower the value, the faster the animation. You do not need to
    specify the number of frames in the Acticon as this information is
    contained in the graphic file created by ICONEDIT. Let's take a look:

    Acticon myicon;
    myicon.init(10,10,"paint");
    myicon.show(0);

    while(!kbhit()) {
        if(leftmousekeypressed()) {
            if(myicon.hit()) {
                while(leftmousekeypressed())
                    myicon.animate(3);
                }
            }
        }

    In this code fragment, if the left mouse key is pressed while the
    cursor is on the Acticon, then the Acticon will animate for as long
    as the left mouse key is pressed. Note that "animate()" and
    "backforth()" will only change the animation by one frame, so for
    continuous motion you must include calls to these methods within
    some sort of loop.





****************************************************************************
                 GSTRINGS
****************************************************************************

    No, it's not something a stripper wears, the G in Gstring simply
    stands for graphic. These object are used for getting text input
    while in graphics mode. They display their own input fields and can
    handle all of the text editing keys like arrows, backspace, delete,
    etc...

Class Gstring is defined as:

class Gstring:public Tstring {
    protected:
        int curpos;                     CURSOR POSITION IN STRING
        int curson;                     CURSOR ON OR OFF
        void showcurs();
        void hidecurs();
    public:
        void init(int xpos,int ypos,int length,int caps);
        void show();
        void input();
        void get_input();
        void get_form_input();
        int isshown();
        void check_for_blink();
    };

    Once again a call to "init()" is necessary to begin. The necessary
    parameters are the x and y coordinates of the upper left corner of
    the input field, the length of the field, and an integer flag to
    indicate whether of not to force the input into all capital letters.
    Any nonzero value will force all caps.

    Notice that Gstring is not derived from class Point as are all the
    other object, but is derived from class Tstring. Tstring is not a
    part of this graphics library, but performs the same functions as
    Gstring only in text mode.

    Two methods that are part of Tstring that you might find useful are
    "preset()" and "reset()." Call "preset()" with a string parameter
    that you wish to have displayed in the input field by default, and
    "reset()" with no parameters to clear the input field. For example,
    if you wanted the input field to be displayed with the preset value
    of "Married" you would use code similar to the following:

    Gstring mystring;
    mystring.init(100,10,10,0);
    mystring.preset("Married");
    mystring.show();

    If you don't use the "preset()" method the input field will just
    be blank, probably what you want in most cases anyway. To allow
    user input just add the statement:

    mystring.get_input();

    This will allow text input until the user presses either <ESCAPE>
    or <ENTER>. You can test for the <ESCAPE> key with the Tstring
    method "escapehit()." Let's put it all together...

    Gstring mystring;
    char *the_string;

    mystring.init(100,10,10,0);
    mystring.get_input();
    if(mystring.escapehit())
        exit(0);
    else
    strcpy(the_string,mystring.getstring());

    The Tstring method "getstring()" returns a char * to the actual
    text string that was entered by the user.





****************************************************************************
               GMENUBUTTON and GMENU
****************************************************************************


    The classes Gmenubutton and Gmenu provide the capabilities for you
    to include pulldown menus in you graphics applications. The
    Gmenubutton is simply the text that will appear in the menu bar
    whereas the Gmenu is the moving bar menu that will pop up when a
    Gmenubutton is selected. Since these two objects are so closely
    related I will discuss them together. Here are the definitions:

class Gmenu {
      protected:
        int on;
        int x,y,w,h;
        int num;
        gitemarray gitems;
        int menuchoice;
        int oldbarx,oldbary;
        void *ptr;
        void *menubar;
      public:
        Gmenu();
        ~Gmenu();
        void init(int xloc,int yloc,int numentries,
               gitemarray gitem);
        int show();
        void hide();
        int isshown();
      };

class Gmenubutton {
        protected:
          int on;
          int x,y;
          int offfgd,offbgd;
          int onfgd,onbgd;
          char id[20];
        public:
          Gmenubutton();
          ~Gmenubutton();
          void init(int xloc,int yloc,int ffgd,int fbgd,
                int nfgd,int nbgd,char txt[20]);
          void show();
          void press();
          int hit();
          };

    The data element gitemarray is a predefined two dimensional
    array containing the strings that will appear in the Gmenu.
    The maximum number of items in a Gmenu is 10, and the width of
    the pop-up menu is fixed at 100 pixels. When initializing the
    strings in the gitemarray always start at index 1 rather than
    index 0. Like this:

    gitemarray menu1array;
    strcpy(menu1array[1],"ITEM 1");
    strcpy(menu1array[2],"ITEM 2");
    etc...

    A Gmenubutton is initialized with parameters for x and y screen
    locations, normal state fgd and bgd colors, selected state fgd
    and bgd colors, and the text to be displayed.

    A Gmenu is initialized with parameters for the x and y screen
    locations, the number of entries to be in the menu, and the
    gitemarray containing the item strings. The Gmenu is popped-up
    with a call to "show()" which returns an integer representing the
    index of the gitemarray the bar was on when the selection was made.
    If no selection was made "show()" returns 11.

    Let's look at an example to hopefully clear this all up.

    gitemarray itemarray;
    Gmenu mymenu;
    Gmenubutton mymenubutton;
    int menuchoice;

    strcpy(itemarray[1],"ITEM 1");
    strcpy(itemarray[2],"ITEM 2");
    strcpy(itemarray[3],"ITEM 3");
    strcpy(itemarray[4],"ITEM 4");

    setfillstyle(SOLID_FILL,15);        MAKE A MENU BAR AT TOP OF SCREEN
    bar(0,0,getmaxx(),10);

    mymenubutton.init(0,0,0,15,15,0,"MENU 1");
    mymenubutton.show();

    mymenu.init(0,11,4,itemarray);

    if(leftmousekeypressed()) {
        if(mymenubutton.hit()) {
            mymenubutton.press();
            choice=mymenu.show();
            mymenu.hide();
            mymenubutton.show();
            }
        }


    In this example the integer variable choice will contain the
    number of the item that was selected. Execution can then branch
    to the appropriate functions based on this value using case
    statements.





***************************************************************************
                PRINTING TEXT
***************************************************************************

    Although not part of a class library, there is a text output
function included in the library that you will find most useful. The
"outtextxy()" function which is part of the Borland library will only
take a char* as the parameter to write to the screen. You cannot give
it a variable to format into a string for you. There is a function in the
GUI_LIB library called gprintxy() that will format variables into
printable text for you. The definition is:

    gprintxy(int,int,char *fmt,...)

    You can use this function just as you would the "printf()" function
in text mode. So for example you could write:

    int age=27;
    gprintxy(100,100,"%d",age);

    "gprintxy()" will format the variable and print it to the screen
correctly. The two integer parameters represent the x and y position to
print the string. Remember that this function is dependent on the current
text justification settings. Use the Borland library function
"settextjustify()" to alter these settings.



****************************************************************************
               MOUSE FUNCTIONS
****************************************************************************

    In this section I will briefly describe the functions associated
    with the mouse. These functions comply with the Microsoft mouse
    driver, however, they may not represent all of the available
    function of this driver.

    The available functions are as follows:

int     mouse_init()    returns 1 if mouse driver is installed, 0 if it
            cannot detect a mouse driver.
void    show_cursor()   makes the mouse cursor visible.
void    hide_cursor()   makes the mouse cursor invisible.
void    pos_mouse(int,int)      sets the mouse cursor position to the x,y
                coordinates given as parameters.
void    sethbounds(int,int)     sets the minimum and maximum horizontal
                mouse cursor boundaries according to the
                parameters.
void    setvbounds(int,int)     sets the minimum and maximum vertical mouse
                cursor boundaries according to the
                parameters.
int     leftmousekeypressed()   returns 1 if the left mouse key is pressed,
                0 otherwise.
int     rightmousekeypressed()  returns 1 if the right mouse key is pressed,
                0 otherwise.

    Future releases of the GUI_LIB library will include the ability
    to select from a number of available graphics cursors.


    Well, that about does it. I'm sure that this being the first
    version of the documentation I will remember some things I should
    have included after it has already been distributed. Oh well, that's
    what revisions are for. That's also what registration and telephone
    support are all about. If you find that you are having trouble
    getting something to work then be prepared to register your copy
    of the package before being able to call for support. This is an
    unregistered copy and is meant for demonstration and evaluation
    purposes. I know for a fact that all of the methods contained in
    the library work correctly. I may have not given clear enough
    directions in this documentation, but if I find that to be the
    case I will correct the documentation. I cannot give phone
    support to unregistered users. Sorry.

    Don't forget to use the registration form in the file REGISTER.DOC
    to register your copy of this library package. I feel that it is
    good quality and very useful software that is well worth the price
    that I am asking.



           Thank you for using software from LUDICROUS DATA


    Note: Refer to the file ICONEDIT.DOC in the ICONEDIT directory for
a description of the use of the ICONEDIT program.